home *** CD-ROM | disk | FTP | other *** search
aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) NNNNAAAAMMMMEEEE asparseopts - parse standard array services command line options SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>> aaaassssooooppppttttiiiinnnnffffoooo____tttt ****aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((iiiinnnntttt aaaarrrrggggcccc,,,, cccchhhhaaaarrrr ********aaaarrrrggggvvvv,,,, iiiinnnntttt SSSSeeeelllleeeecccctttt,,,, iiiinnnntttt CCCCoooonnnnttttrrrroooollll))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The _a_s_p_a_r_s_e_o_p_t_s function is used to parse standard array services command line options from a list of strings, presumably the list of arguments to an array services client program. The results are returned in the form of as aaaassssooooppppttttiiiinnnnffffoooo____tttt structure, which contains parsed, validated values for the options specified in the argument list, as well as a list of the arguments that were not recognized as one of the selected array services options. The aaaarrrrggggcccc and aaaarrrrggggvvvv arguments are an argument count and argument list, in the form typically provided to the function mmmmaaaaiiiinnnn of an ordinary C program. The SSSSeeeelllleeeecccctttt argument is used to specify which of the "standard" array service command line options are to be included in this operation. It is formed from the logical OR of one or more of the following flags, which are defined in <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>>: _AAAA_SSSS_OOOO_IIII_VVVV______AAAA_RRRR_RRRR_AAAA_YYYY Parse the ----aaaarrrrrrrraaaayyyy option, which takes the name of an array as a subargument. ----aaaa is a synonym for the ----aaaarrrrrrrraaaayyyy option. _AAAA_SSSS_OOOO_IIII_VVVV______AAAA_SSSS_HHHH Parse the ----aaaasssshhhh option, which takes an array session handle as a subargument. The array session handle may be specified in decimal, octal (if preceded by "0") or hexadecimal (if preceded by "0x"). ----hhhh and ----aaaarrrrsssseeeessssssss are both synonyms for the ----aaaasssshhhh option. _AAAA_SSSS_OOOO_IIII_VVVV______CCCC_OOOO_NNNN_NNNN_EEEE_CCCC_TTTT_TTTT_OOOO Parse the ----ccccoooonnnnnnnneeeeccccttttttttoooo option, which takes a connection timeout value as a subargument. The value must be specified in decimal only. ----CCCC is a synonym for the ----ccccoooonnnnnnnneeeeccccttttttttoooo option. _AAAA_SSSS_OOOO_IIII_VVVV______FFFF_OOOO_RRRR_WWWW_AAAA_RRRR_DDDD Parses the ----ffffoooorrrrwwwwaaaarrrrdddd and ----ddddiiiirrrreeeecccctttt options, which specify the array services forwarding mode; ----ffffoooorrrrwwwwaaaarrrrdddd indicates that array services commands should be forwarded to their ultimate destination via the server on the local machine, while ----ddddiiiirrrreeeecccctttt means that array services commands should be sent directly to the remote server. ----FFFF is a synonym for the ----ffffoooorrrrwwwwaaaarrrrdddd option and ----DDDD is a synonym for the ----ddddiiiirrrreeeecccctttt option. PPPPaaaaggggeeee 1111 aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) _AAAA_SSSS_OOOO_IIII_VVVV______LLLL_CCCC_LLLL_KKKK_EEEE_YYYY Parse the ----llllooooccccaaaallllkkkkeeeeyyyy option, which takes the authentication key for the local machine as a subargument. ----KKKKllll is a synonym for the ----llllooooccccaaaallllkkkkeeeeyyyy option. _AAAA_SSSS_OOOO_IIII_VVVV______LLLL_OOOO_CCCC_AAAA_LLLL Parse the ----llllooooccccaaaallll option, which indicates that an array services function should take place only on the local server, as opposed to being broadcast to all of the servers in an array, for example. ----llll is a synonym for the ----llllooooccccaaaallll option. _AAAA_SSSS_OOOO_IIII_VVVV______PPPP_IIII_DDDD Parse the ----ppppiiiidddd option, which takes a process ID as a subargument. The process ID should be specified in decimal only and must be positive. ----iiii and ----pppprrrroooocccceeeessssssss are both synonyms for the ----ppppiiiidddd option. _AAAA_SSSS_OOOO_IIII_VVVV______PPPP_OOOO_RRRR_TTTT_NNNN_UUUU_MMMM Parse the ----ppppoooorrrrttttnnnnuuuummmm option, which takes a port number as a subargument. The port number should be specified in decimal only and must be in the range 1-65535. ----pppp is a synonym for the ----ppppoooorrrrttttnnnnuuuummmm option. _AAAA_SSSS_OOOO_IIII_VVVV______RRRR_EEEE_MMMM_KKKK_EEEE_YYYY Parse the ----rrrreeeemmmmooootttteeeekkkkeeeeyyyy option, which takes the authentication key for a remote machine as a subargument. ----KKKKrrrr is a synonym for the ----rrrreeeemmmmooootttteeeekkkkeeeeyyyy option. _AAAA_SSSS_OOOO_IIII_VVVV______SSSS_EEEE_RRRR_VVVV_EEEE_RRRR Parse the ----sssseeeerrrrvvvveeeerrrr option, which takes the hostname of an array daemon as a subargument. ----ssss is a synonym for the ----sssseeeerrrrvvvveeeerrrr option. _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_IIII_MMMM_EEEE_OOOO_UUUU_TTTT Parse the ----ttttiiiimmmmeeeeoooouuuutttt option, which takes a timeout value as a subargument. The value must be specified in decimal only. ----tttt is a synonym for the ----ttttiiiimmmmeeeeoooouuuutttt option. _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN If this flag is specified and no invalid arguments were encountered (in other words, the iiiinnnnvvvvaaaalllliiiidddd member of the returned asoptinfo_t is 0), then a server token using the parsed options will be created using _a_s_o_p_e_n_s_e_r_v_e_r__f_r_o_m__o_p_t_i_n_f_o(3X). _AAAA_SSSS_OOOO_IIII_VVVV______VVVV_EEEE_RRRR_BBBB_OOOO_SSSS_EEEE Parse the ----vvvv option, which is used to set a verbosity level. The default verbose level is 0, and each occurrence of ----vvvv will increase the level by 1. If an option begins with "v" and is followed by any number of other non-whitespace characters (for example, "-vvv"), then the verbose level is increased by the number of characters following the hyphen (3 in the case of "-vvv"). PPPPaaaaggggeeee 2222 aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) The CCCCoooonnnnnnnneeeecccctttt argument is used to specify flags which modify the parsing behavior. It is formed from the logical OR of zero or more of the following flags, which are defined in <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>>: _AAAA_SSSS_OOOO_IIII_CCCC______LLLL_OOOO_GGGG_EEEE_RRRR_RRRR_SSSS Specifies that syntax errors and other abnormal conditions should be reported to the normal array services error logging destination, which is typically _s_t_d_e_r_r. If this flag is not specified no error messages will be generated, but the iiiinnnnvvvvaaaalllliiiidddd member of the returned asoptinfo_t can still be checked to determine if any errors were detected. _AAAA_SSSS_OOOO_IIII_CCCC______NNNN_OOOO_DDDD_UUUU_PPPP_SSSS Ordinarily, if an option is specified more than once, the last occurrence of the option in the argument list will quietly override any previous occurrences of the option. If the ASOIC_NODUPS flag is specified, then duplicate occurrences will be called out as errors and the option will be marked as invalid in the returned asoptinfo_t. _AAAA_SSSS_OOOO_IIII_CCCC______OOOO_PPPP_TTTT_SSSS_OOOO_NNNN_LLLL_YYYY This flag causes parsing to stop as soon as an argument which does not begin with a "-" character is encountered (not including subarguments to valid options). The "non-option" argument and all arguments following it will be returned as unrecognized arguments, even if some of the subsequent arguments would otherwise have been valid array services options. _AAAA_SSSS_OOOO_IIII_CCCC______SSSS_EEEE_LLLL_OOOO_NNNN_LLLL_YYYY This is similar to _AAAA_SSSS_OOOO_IIII_CCCC______OOOO_PPPP_TTTT_SSSS_OOOO_NNNN_LLLL_YYYY with the added restriction that parsing stops as soon as _a_n_y argument which is not a selected option or the subargument of a selected option is encountered. If the argument list is successfully parsed, a pointer to an aaaassssooooppppttttiiiinnnnffffoooo____tttt structure (also defined in <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>>) is returned. The storage for this structure is allocated using _m_a_l_l_o_c(3C) and can be released using the _a_s_f_r_e_e_o_p_t_i_n_f_o(3X) function. An aaaassssooooppppttttiiiinnnnffffoooo____tttt structure looks similar to this: typedef struct asoptinfo { int argc; char **argv; int valid; int invalid; int options; asserver_t token; char *server; char *array; askey_t localkey; askey_t remotekey; ash_t ash; pid_t pid; PPPPaaaaggggeeee 3333 aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) int portnum; int timeout; int connectto; int verbose; } asoptinfo_t; The aaaarrrrggggcccc and aaaarrrrggggvvvv members are a count and list, respectively, of arguments that were not recognized as selected array services options or their corresponding subarguments. The vvvvaaaalllliiiidddd member is a bitmap used to specify which options were successfully parsed and are present in the asoptinfo_t. The same flags used to specify the SSSSeeeelllleeeecccctttt argument to _a_s_p_a_r_s_e_o_p_t_s are used to indicate which options are present. The iiiinnnnvvvvaaaalllliiiidddd member is a bitmap of options that were selected and specified in the argument list, but had values which were invalid in some way. If the _AAAA_SSSS_OOOO_IIII_CCCC______LLLL_OOOO_GGGG_EEEE_RRRR_RRRR_SSSS control flag was specified, then an error message explaining the nature of the problem should already have been generated. This member also uses the same flags as vvvvaaaalllliiiidddd and SSSSeeeelllleeeecccctttt. The ooooppppttttiiiioooonnnnssss member is a bitmap of flags indicating the state of the various binary options. These include: ASOIO_FORWARD If set, command forwarding has been requested. Otherwise, a direct connection is desired. ASOIO_LOCAL If set, the command should be restricted to the local server. Otherwise, it may be considered eligible for broadcast to all servers in an array. IMPORTANT: A flag in ooooppppttttiiiioooonnnnssss should only be examined if it is also marked as valid in vvvvaaaalllliiiidddd. For example, the state of the _AAAA_SSSS_OOOO_IIII_OOOO______FFFF_OOOO_RRRR_WWWW_AAAA_RRRR_DDDD flag in ooooppppttttiiiioooonnnnssss is only meaningful if the _AAAA_SSSS_OOOO_IIII_VVVV______FFFF_OOOO_RRRR_WWWW_AAAA_RRRR_DDDD flag is set in vvvvaaaalllliiiidddd. If the appropriate flag in vvvvaaaalllliiiidddd is _n_o_t set, then the option should be considered unspecified and a default setting should be used instead. The ttttooookkkkeeeennnn member of aaaassssooooppppttttiiiinnnnffffoooo____tttt is not a value directly parsed from the argument list, but instead a server token created using the values that were successfully parsed from the argument list. It will only be created if the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag was set in SSSSeeeelllleeeecccctttt. If it is successfully created, the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag will be set in the vvvvaaaalllliiiidddd member of the aaaassssooooppppttttiiiinnnnffffoooo____tttt. Otherwise, _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN will be set in the iiiinnnnvvvvaaaalllliiiidddd member and _a_s_e_r_r_o_r_c_o_d_e(3X) will be set accordingly. The remaining members of the aaaassssooooppppttttiiiinnnnffffoooo____tttt contain the values of the selected array services options. If a selected option was specified in the argument list, then its flag in vvvvaaaalllliiiidddd will be set and the PPPPaaaaggggeeee 4444 aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx)))) corresponding member of aaaassssooooppppttttiiiinnnnffffoooo____tttt will contain the parsed value of that option. If a selected option was _n_o_t specified in the argument list, then its flag in vvvvaaaalllliiiidddd will not be set and the corresponding member of aaaassssooooppppttttiiiinnnnffffoooo____tttt will contain a default value (generally NULL, 0 or -1, as appropriate). If a selected option had an invalid value, then its flag will be set in iiiinnnnvvvvaaaalllliiiidddd and the contents of the corresponding member of aaaassssooooppppttttiiiinnnnffffoooo____tttt are unpredictable. NNNNOOOOTTTTEEEESSSS _a_s_p_a_r_s_e_o_p_t_s is found in the library "libarray.so", and will be loaded if the option "-larray" is used with _c_c(1) or _l_d(1). SSSSEEEEEEEE AAAALLLLSSSSOOOO aserrorcode(3X), asfreeoptinfo(3X), asopenserver_from_optinfo(3X), DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS If successful, _a_s_p_a_r_s_e_o_p_t_s returns a pointer to an aaaassssooooppppttttiiiinnnnffffoooo____tttt structure. If a severe error occurs, NULL is returned and _a_s_e_r_r_o_r_c_o_d_e is set appropriately. If _a_s_p_a_r_s_e_o_p_t_s is successful and the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag of SSSSeeeelllleeeecccctttt was specified but a server token could not be created, the pointer to the aaaassssooooppppttttiiiinnnnffffoooo____tttt will be returned as usual, but the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag of the iiiinnnnvvvvaaaalllliiiidddd member will be set and _a_s_e_r_r_o_r_c_o_d_e will contain the error returned by _a_s_o_p_e_n_s_e_r_v_e_r__f_r_o_m__o_p_t_i_n_f_o(3X). PPPPaaaaggggeeee 5555 
